IRIX Base Documentation 1998 November

home *** CD-ROM | disk | FTP | other *** search

/ IRIX Base Documentation 1998 November / IRIX 6.5.2 Base Documentation November 1998.img / usr / share / catman / p_man / cato / Xm / UIL.z / UIL

Wrap

Text File | 1998-10-20 | 119KB | 2,179 lines

UUUUIIIILLLL((((5555XXXX)))) UUUUNNNNIIIIXXXX SSSSyyyysssstttteeeemmmm VVVV UUUUIIIILLLL((((5555XXXX)))) NNNNAAAAMMMMEEEE UUUUIIIILLLL - The user interface language file format SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS MMMMOOOODDDDUUUULLLLEEEE _m_o_d_u_l_e__n_a_m_e [ NNNNAAAAMMMMEEEESSSS ==== CCCCAAAASSSSEEEE____IIIINNNNSSSSEEEENNNNSSSSIIIITTTTIIIIVVVVEEEE | CCCCAAAASSSSEEEE____SSSSEEEENNNNSSSSIIIITTTTIIIIVVVVEEEE ] [ CCCCHHHHAAAARRRRAAAACCCCTTTTEEEERRRR____SSSSEEEETTTT ==== _c_h_a_r_a_c_t_e_r__s_e_t ] [ OOOOBBBBJJJJEEEECCCCTTTTSSSS ==== {{{{ _w_i_d_g_e_t__n_a_m_e ==== GGGGAAAADDDDGGGGEEEETTTT | WWWWIIIIDDDDGGGGEEEETTTT;;;; [...] }}}} ] {{{{ [ [ _v_a_l_u_e__s_e_c_t_i_o_n ] | [ _p_r_o_c_e_d_u_r_e__s_e_c_t_i_o_n ] | [ _l_i_s_t__s_e_c_t_i_o_n ] | [ _o_b_j_e_c_t__s_e_c_t_i_o_n ] | [ _i_d_e_n_t_i_f_i_e_r__s_e_c_t_i_o_n ] [ ... ] ] }}}} EEEENNNNDDDD MMMMOOOODDDDUUUULLLLEEEE;;;; DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN The UIL language is used for describing the initial state of a user interface for a widget based application. UIL describes the widgets used in the interface, the resources of those widgets, and the callbacks of those widgets. The UIL file is compiled into a UID file using the command uuuuiiiillll or by the callable compiler UUUUiiiillll(((()))). The contents of the compiled UID file can then by accessed by the various Motif Resource Management (MRM) functions from within an application program. FFFFIIIILLLLEEEE FFFFOOOORRRRMMMMAAAATTTT UIL is a free-form language. This means that high-level constructs such as object and value declarations do not need to begin in any particular column and can span any number of lines. Low-level constructs such as keywords and punctuation characters can also begin in any column; however, except for string literals and comments, they cannot span lines. The UIL compiler accepts input lines up to 132 characters in length. MMMMOOOODDDDUUUULLLLEEEE _m_o_d_u_l_e__n_a_m_e The name by which the UIL module is known in the UID file. This name is stored in the UID file for later use in the retrieval of resources by the MRM. This name is always stored in uppercase in the UID file. NNNNAAAAMMMMEEEESSSS ==== CCCCAAAASSSSEEEE____IIIINNNNSSSSEEEENNNNSSSSIIIITTTTIIIIVVVVEEEE | CCCCAAAASSSSEEEE____SSSSEEEENNNNSSSSIIIITTTTIIIIVVVVEEEE Indicates whether names should be treated as case sensitive or case insensitive. The default is case sensitive. The case-sensitivity clause should Page 1 (printed 4/30/98) UUUUIIIILLLL((((5555XXXX)))) UUUUNNNNIIIIXXXX SSSSyyyysssstttteeeemmmm VVVV UUUUIIIILLLL((((5555XXXX)))) be the first clause in the module header, and in any case must precede any statement that contains a name. If names are case sensitive in a UIL module, UIL keywords in that module must be in lowercase. Each name is stored in the UIL file in the same case as it appears in the UIL module. If names are case insensitive, then keywords can be in uppercase, lowercase, or mixed case, and the uppercase equivalent of each name is stored in the UID file. CCCCHHHHAAAARRRRAAAACCCCTTTTEEEERRRR____SSSSEEEETTTT ==== _c_h_a_r_a_c_t_e_r__s_e_t Specifies the default character set for string literals in the module that do not explicitly set their character set. The default character set, in the absence of this clause is the codeset component of the LLLLAAAANNNNGGGG environment variable, or the value of XXXXmmmmFFFFAAAALLLLLLLLBBBBAAAACCCCKKKK____CCCCHHHHAAAARRRRSSSSEEEETTTT if LLLLAAAANNNNGGGG is not set or has no codeset component. The value of XXXXmmmmFFFFAAAALLLLLLLLBBBBAAAACCCCKKKK____CCCCHHHHAAAARRRRSSSSEEEETTTT is defined by UIL supplier, but is usually ISO8859-1 (equivalent to ISO_LATIN1). Use of this clause turns off all localized string literal processing turned on by the compiler flag ----ssss or the UUUUiiiillll____ccccoooommmmmmmmaaaannnndddd____ttttyyyyppppeeee ddddaaaattttaaaa ssssttttrrrruuuuccccttttuuuurrrreeee eeeelllleeeemmmmeeeennnntttt uuuusssseeee____sssseeeettttllllooooccccaaaalllleeee____ffffllllaaaagggg. OOOOBBBBJJJJEEEECCCCTTTTSSSS ==== {{{{ _w_i_d_g_e_t__n_a_m_e = GGGGAAAADDDDGGGGEEEETTTT | WWWWIIIIDDDDGGGGEEEETTTT;;;; }}}} Indicates whether the widget or gadget form of the control specified by _w_i_d_g_e_t__n_a_m_e is used by default. By default the widget form is used, so the gadget keyword is usually the only one used. The specified control should be one that has both a widget and gadget version: XmCascadeButton, XmLabel, XmPushButton, XmSeparator, and XmToggleButton. The form of more than one control can be specified by delimiting them with semicolons. The gadget or widget form of an instance of a control can be specified with the GGGGAAAADDDDGGGGEEEETTTT and WWWWIIIIDDDDGGGGEEEETTTT keywords in a particular object declaration. _v_a_l_u_e__s_e_c_t_i_o_n Provides a way to name a value expression or literal. The value name can then be referred to by declarations that occur elsewhere in the UIL module in any context where a value can be used. Values can be forward referenced. Value sections are described in more detail later in the reference page. _p_r_o_c_e_d_u_r_e__s_e_c_t_i_o_n Defines the callback routines used by a widget and Page 2 (printed 4/30/98) UUUUIIIILLLL((((5555XXXX)))) UUUUNNNNIIIIXXXX SSSSyyyysssstttteeeemmmm VVVV UUUUIIIILLLL((((5555XXXX)))) the creation routines for user-defined widgets. These definitions are used for error checking. Procedure sections are described in more detail later in the reference page. _l_i_s_t__s_e_c_t_i_o_n Provides a way to group together a set of arguments, controls (children), callbacks, or procedures for later use in the UIL module. Lists can contain other lists, so that you can set up a hierarchy to clearly show which arguments, controls, callbacks, and procedures are common to which widgets. List sections are described in more detail later in the reference page. _o_b_j_e_c_t__s_e_c_t_i_o_n Defines the objects that make up the user interface of the application. You can reference the object names in declarations that occur elsewhere in the UIL module in any context where an object name can be used (for example, in a controls list, as a symbolic reference to a widget ID, or as the tag_value argument for a callback procedure). Objects can be forward referenced. Object sections are described in more detail later in the reference page. _i_d_e_n_t_i_f_i_e_r__s_e_c_t_i_o_n Defines a run-time binding of data to names that appear in the UIL module. Identifier sections are described in more detail later in the reference page. The UIL file can also contain comments and include directives, which are described along with the main elements of the UIL file format in the following sections. CCCCoooommmmmmmmeeeennnnttttssss Comments can take one of two forms, as follows: +o The comment is introduced with the sequence ////**** followed by the text of the comment and terminated with the sequence ****////. This form of comment can span multiple source lines. +o The comment is introduced with an !!!! (exclamation point), followed by the text of the comment and terminated by the end of the source line. Page 3 (printed 4/30/98) UUUUIIIILLLL((((5555XXXX)))) UUUUNNNNIIIIXXXX SSSSyyyysssstttteeeemmmm VVVV UUUUIIIILLLL((((5555XXXX)))) Neither form of comment can be nested. VVVVaaaalllluuuueeee sssseeeeccccttttiiiioooonnnnssss A value section consists of the keyword VVVVAAAALLLLUUUUEEEE followed by a sequence of value declarations. It has the following syntax: VVVVAAAALLLLUUUUEEEE _v_a_l_u_e__n_a_m_e :::: [ EEEEXXXXPPPPOOOORRRRTTTTEEEEDDDD | PPPPRRRRIIIIVVVVAAAATTTTEEEE ] _v_a_l_u_e__e_x_p_r_e_s_s_i_o_n | IIIIMMMMPPPPOOOORRRRTTTTEEEEDDDD _v_a_l_u_e__t_y_p_e ;;;; Where _v_a_l_u_e__e_x_p_r_e_s_s_i_o_n is assigned to _v_a_l_u_e__n_a_m_e or a _v_a_l_u_e__t_y_p_e is assigned to an imported value name. A value declaration provides a way to name a value expression or literal. The value name can be referred to by declarations that occur later in the UIL module in any context where a value can be used. Values can be forward referenced. EEEEXXXXPPPPOOOORRRRTTTTEEEEDDDD A value that you define as exported is stored in the UID file as a named resource, and therefore can be referenced by name in other UID files. When you define a value as exported, MRM looks outside the module in which the exported value is declared to get its value at run time. PPPPRRRRIIIIVVVVAAAATTTTEEEE A private value is a value that is not imported or exported. A value that you define as private is not stored as a distinct resource in the UID file. You can reference a private value only in the UIL module containing the value declaration. The value or object is directly incorporated into anything in the UIL module that references the declaration. IIIIMMMMPPPPOOOORRRRTTTTEEEEDDDD A value that you define as imported is one that is defined as a named resource in a UID file. MRM resolves this declaration with the corresponding exported declaration at application run time. By default, values and objects are private. The following is a list of the supported value types in UIL. +o AAAANNNNYYYY +o AAAARRRRGGGGUUUUMMMMEEEENNNNTTTT +o BBBBOOOOOOOOLLLLEEEEAAAANNNN +o CCCCOOOOLLLLOOOORRRR Page 4 (printed 4/30/98) UUUUIIIILLLL((((5555XXXX)))) UUUUNNNNIIIIXXXX SSSSyyyysssstttteeeemmmm VVVV UUUUIIIILLLL((((5555XXXX)))) +o CCCCOOOOLLLLOOOORRRR____TTTTAAAABBBBLLLLEEEE +o CCCCOOOOMMMMPPPPOOOOUUUUNNNNDDDD____SSSSTTTTRRRRIIIINNNNGGGG +o FFFFLLLLOOOOAAAATTTT +o FFFFOOOONNNNTTTT +o FFFFOOOONNNNTTTT____TTTTAAAABBBBLLLLEEEE +o FFFFOOOONNNNTTTTSSSSEEEETTTT +o IIIICCCCOOOONNNN +o IIIINNNNTTTTEEEEGGGGEEEERRRR +o IIIINNNNTTTTEEEEGGGGEEEERRRR____TTTTAAAABBBBLLLLEEEE +o KKKKEEEEYYYYSSSSYYYYMMMM +o RRRREEEEAAAASSSSOOOONNNN +o SSSSIIIINNNNGGGGLLLLEEEE____FFFFLLLLOOOOAAAATTTT +o SSSSTTTTRRRRIIIINNNNGGGG +o SSSSTTTTRRRRIIIINNNNGGGG____TTTTAAAABBBBLLLLEEEE +o TTTTRRRRAAAANNNNSSSSLLLLAAAATTTTIIIIOOOONNNN____TTTTAAAABBBBLLLLEEEE +o WWWWIIIIDDDDEEEE____CCCCHHHHAAAARRRRAAAACCCCTTTTEEEERRRR +o WWWWIIIIDDDDGGGGEEEETTTT PPPPrrrroooocccceeeedddduuuurrrreeee sssseeeeccccttttiiiioooonnnnssss A procedure section consists of the keyword PPPPRRRROOOOCCCCEEEEDDDDUUUURRRREEEE followed by a sequence of procedure declarations. It has the following syntax: PPPPRRRROOOOCCCCEEEEDDDDUUUURRRREEEE _p_r_o_c_e_d_u_r_e__n_a_m_e [ (((( [ _v_a_l_u_e__t_y_p_e ] )))) ] ;;;; Use a procedure declaration to declare: +o A routine that can be used as a callback routine for a widget +o The creation function for a user-defined widget Page 5 (printed 4/30/98) UUUUIIIILLLL((((5555XXXX)))) UUUUNNNNIIIIXXXX SSSSyyyysssstttteeeemmmm VVVV UUUUIIIILLLL((((5555XXXX)))) You can reference a procedure name in declarations that occur later in the UIL module in any context where a procedure can be used. Procedures can be forward referenced. You cannot use a name you used in another context as a procedure name. In a procedure declaration, you have the option of specifying that a parameter will be passed to the corresponding callback routine at run time. This parameter is called the callback tag. You can specify the data type of the callback tag by putting the data type in parentheses following the procedure name. When you compile the module, the UIL compiler checks that the argument you specify in references to the procedure is of this type. Note that the data type of the callback tag must be one of the valid UIL data types. You can use a widget as a callback tag, as long as the widget is defined in the same widget hierarchy as the callback, that is they have a common ancestor that is in the same UIL hierarchy. The following list summarizes how the UIL compiler checks argument type and argument count, depending on the procedure declaration. No parameters No argument type or argument count checking occurs. You can supply either 0 or 1 aguments in the prcedure reference. (((( )))) Checks that the argument count is 0. ((((AAAANNNNYYYY)))) Checks that the argument count is 1. Does not check the argument type. Use the AAAANNNNYYYY type to prevent type checking on procedure tags. ((((_t_y_p_e)))) Checks for one argument of the specified type. ((((_c_l_a_s_s__n_a_m_e)))) Checks for one widget argument of the specified widget class. While it is possible to use any UIL data type to specify the type of a tag in a procedure declaration, you must be able to represent that data type in the programming language you are using. Some data types (such as integer, Boolean, and string) are common data types recognized by most programming languages. Other UIL data types (such as string tables) are more complicated and may require you to set up an appropriate corresponding data structure in the application in order to pass a tag of that type to a callback routine. Page 6 (printed 4/30/98) UUUUIIIILLLL((((5555XXXX)))) UUUUNNNNIIIIXXXX SSSSyyyysssstttteeeemmmm VVVV UUUUIIIILLLL((((5555XXXX)))) You can also use a procedure declaration to specify the creation function for a user-defined widget. In this case, you specify no formal parameters. The procedure is invoked with the standard three arguments passed to all widget creation functions. (See the Motif Toolkit documentation for more information about widget creation functions.) LLLLiiiisssstttt sssseeeeccccttttiiiioooonnnnssss A list section consists of the keyword LLLLIIIISSSSTTTT followed by a sequence of list declarations. It has the following syntax: LLLLIIIISSSSTTTT _l_i_s_t__n_a_m_e :::: {{{{ _l_i_s_t__i_t_e_m;;;; [...] }}}} [...] You can also use list sections to group together a set of arguments, controls (children), callbacks, or procedures for later use in the UIL module. Lists can contain other lists, so that you can set up a hierarchy to clearly show which arguments, controls, callbacks, and procedures are common to which widgets. You cannot mix the different types of lists; a list of a particular type cannot contain entries of a different list type or reference the name of a different list type. A list name is always private to the UIL module in which you declare the list and cannot be stored as a named resource in a UID file. The additional list types are described in the following sections. AAAArrrrgggguuuummmmeeeennnnttttssss LLLLiiiisssstttt SSSSttttrrrruuuuccccttttuuuurrrreeee An arguments list defines which arguments are to be specified in the arguments-list parameter when the creation routine for a particular object is called at run time. An arguments list also specifies the values for those arguments. Argument lists have the following syntax: LLLLIIIISSSSTTTT _l_i_s_t__n_a_m_e :::: AAAARRRRGGGGUUUUMMMMEEEENNNNTTTTSSSS {{{{ _a_r_g_u_m_e_n_t__n_a_m_e ==== _v_a_l_u_e__e_x_p_r_e_s_s_i_o_n;;;; [...] }}}} [...] The argument name must be either a built-in argument name or a user-defined argument name that is specified with the AAAARRRRGGGGUUUUMMMMEEEENNNNTTTT function. If you use a built-in argument name as an arguments list entry in an object definition, the UIL compiler checks the argument name to be sure that it is supported by the type of object that you are defining. If the same argument name Page 7 (printed 4/30/98) UUUUIIIILLLL((((5555XXXX)))) UUUUNNNNIIIIXXXX SSSSyyyysssstttteeeemmmm VVVV UUUUIIIILLLL((((5555XXXX)))) appears more than once in a given arguments list, the last entry that uses that argument name supersedes all previous entries with that name, and the compiler issues a message. Some arguments, such as XXXXmmmmNNNNiiiitttteeeemmmmssss and XXXXmmmmNNNNiiiitttteeeemmmmCCCCoooouuuunnnntttt, are coupled by the UIL compiler. When you specify one of the arguments, the compiler also sets the other. The coupled argument is not available to you. The Motif Toolkit and the X Toolkit (intrinsics) support constraint arguments. A constraint argument is one that is passed to children of an object, beyond those arguments normally available. For example, the Form widget grants a set of constraint arguments to its children. These arguments control the position of the children within the Form. Unlike the arguments used to define the attributes of a particular widget, constraint arguments are used exclusively to define additional attributes of the children of a particular widget. These attributes affect the behavior of the children within their parent. To supply constraint arguments to the children, you include the arguments in the arguments list for the child. See _A_p_p_e_n_d_i_x _B for information about which arguments are supported by which widgets. See _A_p_p_e_n_d_i_x _C for information about what the valid value type is for each built-in argument. CCCCaaaallllllllbbbbaaaacccckkkkssss LLLLiiiisssstttt SSSSttttrrrruuuuccccttttuuuurrrreeee Use a callbacks list to define which callback reasons are to be processed by a particular widget at run time. Callback lists have the following syntax: LLLLIIIISSSSTTTT _l_i_s_t__n_a_m_e :::: CCCCAAAALLLLLLLLBBBBAAAACCCCKKKKSSSS {{{{ _r_e_a_s_o_n__n_a_m_e ==== PPPPRRRROOOOCCCCEEEEDDDDUUUURRRREEEE _p_r_o_c_e_d_u_r_e__n_a_m_e [[[[ (((( [ _v_a_l_u_e__e_x_p_r_e_s_s_i_o_n ] )))) ];;;; | _r_e_a_s_o_n__n_a_m_e ==== _p_r_o_c_e_d_u_r_e__l_i_s_t ;;;; [...] }}}} [...] For Motif Toolkit widgets, the reason name must be a built- in reason name. For a user-defined widget, you can use a reason name that you previously specified using the RRRREEEEAAAASSSSOOOONNNN function. If you use a built-in reason in an object definition, the UIL compiler ensures that reason is supported by the type of object you are defining. Appendix B shows which reasons each object supports. If the same reason appears more than once in a callbacks Page 8 (printed 4/30/98) UUUUIIIILLLL((((5555XXXX)))) UUUUNNNNIIIIXXXX SSSSyyyysssstttteeeemmmm VVVV UUUUIIIILLLL((((5555XXXX)))) list, the last entry referring to that name supersedes all previous entries using the same reason, and the UIL compiler issues a diagnostic message. If you specify a named value for the procedure argument (callback tag), the data type of the value must match the type specified for the callback tag in the corresponding procedure declaration. When specifying a widget name as a procedure value expression you must also specify the type of the widget and a space before the name of the widget. Because the UIL compiler produces a UID file rather than an object module (.o), the binding of the UIL name to the address of the entry point to the procedure is not done by the loader, but is established at run time with the MRM function MMMMrrrrmmmmRRRReeeeggggiiiisssstttteeeerrrrNNNNaaaammmmeeeessss. You call this function before fetching any objects, giving it both the UIL names and the procedure addresses of each callback. The name you register with MRM in the application program must match the name you specified for the procedure in the UIL module. Each callback procedure receives three arguments. The first two arguments have the same form for each callback. The form of the third argument varies from object to object. The first argument is the address of the data structure maintained by the Motif Toolkit for this object instance. This address is called the widget ID for this object. The second argument is the address of the value you specified in the callbacks list for this procedure. If you do not specify an argument, the address is NULL. The third argument is the reason name you specified in the callbacks list. CCCCoooonnnnttttrrrroooollllssss LLLLiiiisssstttt SSSSttttrrrruuuuccccttttuuuurrrreeee A controls list defines which objects are children of, or controlled by, a particular object. Each entry in a controls list has the following syntax: LLLLIIIISSSSTTTT _l_i_s_t__n_a_m_e :::: CCCCOOOONNNNTTTTRRRROOOOLLLLSSSS {{{{ [_c_h_i_l_d__n_a_m_e] [MMMMAAAANNNNAAAAGGGGEEEEDDDD | UUUUNNNNMMMMAAAANNNNAAAAGGGGEEEEDDDD] _o_b_j_e_c_t__d_e_f_i_n_i_t_i_o_n;;;; [...] }}}} [...] If you specify the keyword MMMMAAAANNNNAAAAGGGGEEEEDDDD at run time, the object is created and managed; if you specify UUUUNNNNMMMMAAAANNNNAAAAGGGGEEEEDDDD at run time, the object is only created. Objects are managed by default. Page 9 (printed 4/30/98) UUUUIIIILLLL((((5555XXXX)))) UUUUNNNNIIIIXXXX SSSSyyyysssstttteeeemmmm VVVV UUUUIIIILLLL((((5555XXXX)))) You can use _c_h_i_l_d__n_a_m_e to specify resources for the automatically created children of a particular control. Names for automatically created children are formed by appending XXXXmmmm____ to the name of the child widget. This name is specified in the documentation for the parent widget. Unlike the arguments list and the callbacks list, a controls list entry that is identical to a previous entry does not supersede the previous entry. At run time, each controls list entry causes a child to be created when the parent is created. If the same object definition is used for multiple children, multiple instances of the child are created at run time. See _A_p_p_e_n_d_i_x _B for a list of which widget types can be controlled by which other widget types. PPPPrrrroooocccceeeedddduuuurrrreeeessss LLLLiiiisssstttt SSSSttttrrrruuuuccccttttuuuurrrreeee You can specify multiple procedures for a callback reason in UIL by defining a procedures list. Just as with other list types, procedures lists can be defined in-line or in a list section and referenced by name. If you define a reason more than once (for example, when the reason is defined both in a referenced procedures list and in the callbacks list for the object), previous definitions are overridden by the latest definition. The syntax for a procedures list is as follows: LLLLIIIISSSSTTTT _l_i_s_t__n_a_m_e :::: PPPPRRRROOOOCCCCEEEEDDDDUUUURRRREEEESSSS {{{{ _p_r_o_c_e_d_u_r_e__n_a_m_e [[[[ (((( [ _v_a_l_u_e__e_x_p_r_e_s_s_i_o_n ] )))) ];;;; [...] }}}} [...] When specifying a widget name as a procedure value expression you must also specify the type of the widget and a space before the name of the widget. OOOObbbbjjjjeeeecccctttt SSSSeeeeccccttttiiiioooonnnnssss An object section consists of the keyword OOOOBBBBJJJJEEEECCCCTTTT followed by a sequence of object declarations. It has the following syntax: OOOOBBBBJJJJEEEECCCCTTTT _o_b_j_e_c_t__n_a_m_e :::: [ EEEEXXXXPPPPOOOORRRRTTTTEEEEDDDD | PPPPRRRRIIIIVVVVAAAATTTTEEEE | IIIIMMMMPPPPOOOORRRRTTTTEEEEDDDD ] _o_b_j_e_c_t__t_y_p_e [ PPPPRRRROOOOCCCCEEEEDDDDUUUURRRREEEE _c_r_e_a_t_i_o_n__f_u_n_c_t_i_o_n ]]]] [[[[ _o_b_j_e_c_t__n_a_m_e [ WWWWIIIIDDDDGGGGEEEETTTT | GGGGAAAADDDDGGGGEEEETTTT ] | {{{{ _l_i_s_t__d_e_f_i_n_i_t_i_o_n_s }}}} ] Use an object declaration to define the objects that are to be stored in the UID file. You can reference the object name in declarations that occur elsewhere in the UIL module in any context where an object name can be used (for Page 10 (printed 4/30/98) UUUUIIIILLLL((((5555XXXX)))) UUUUNNNNIIIIXXXX SSSSyyyysssstttteeeemmmm VVVV UUUUIIIILLLL((((5555XXXX)))) example, in a controls list, as a symbolic reference to a widget ID, or as the tag_value argument for a callback procedure). Objects can be forward referenced; that is, you can declare an object name after you reference it. All references to an object name must be consistent with the type of the object, as specified in the object declaration. You can specify an object as exported, imported, or private. The object definition can contain a sequence of lists that define the arguments, hierarchy, and callbacks for the widget. You can specify only one list of each type for an object. When you declare a user-defined widget, you must include a reference to the widget creation function for the user-defined widget. Use the GGGGAAAADDDDGGGGEEEETTTT or WWWWIIIIDDDDGGGGEEEETTTT keyword to specify the object type or to override the default variant for this object type. You can use the Motif Toolkit name of an object type that has a gadget variant (for example, XXXXmmmmLLLLaaaabbbbeeeellllGGGGaaaaddddggggeeeetttt) as an attribute of an object declaration. The _o_b_j_e_c_t__t_y_p_e can be any object type, including gadgets. You need to specify the GGGGAAAADDDDGGGGEEEETTTT or WWWWIIIIDDDDGGGGEEEETTTT keyword only in the declaration of an object, not when you reference the object. You cannot specify the GGGGAAAADDDDGGGGEEEETTTT or WWWWIIIIDDDDGGGGEEEETTTT keyword for a user-defined object; user-defined objects are always widgets. IIIIddddeeeennnnttttiiiiffffiiiieeeerrrr sssseeeeccccttttiiiioooonnnnssss The identifier section allows you to define an identifier, a mechanism that achieves run-time binding of data to names that appear in a UIL module. The identifier section consists of the reserved keyword IIIIDDDDEEEENNNNTTTTIIIIFFFFIIIIEEEERRRR, followed by a list of names, each name followed by a semicolon. IIIIDDDDEEEENNNNTTTTIIIIFFFFIIIIEEEERRRR _i_d_e_n_t_i_f_i_e_r__n_a_m_e;;;; [...;;;;] You can later use these names in the UIL module as either the value of an argument to a widget or the tag value to a callback procedure. At run time, you use the MRM functions MMMMrrrrmmmmRRRReeeeggggiiiisssstttteeeerrrrNNNNaaaammmmeeeessss and MMMMrrrrmmmmRRRReeeeggggiiiisssstttteeeerrrrNNNNaaaammmmeeeessssIIIInnnnHHHHiiiieeeerrrraaaarrrrcccchhhhyyyy to bind the identifier name with the data (or, in the case of callbacks, with the address of the data) associated with the identifier. Each UIL module has a single name space; therefore, you cannot use a name you used for a value, object, or procedure as an identifier name in the same module. The UIL compiler does not do any type checking on the use of identifiers in a UIL module. Unlike a UIL value, an identifier does not have a UIL type associated with it. Regardless of what particular type a widget argument or callback procedure tag is defined to be, you can use an Page 11 (printed 4/30/98) UUUUIIIILLLL((((5555XXXX)))) UUUUNNNNIIIIXXXX SSSSyyyysssstttteeeemmmm VVVV UUUUIIIILLLL((((5555XXXX)))) identifier in that context instead of a value of the corresponding type. To reference these identifier names in a UIL module, you use the name of the identifier wherever you want its value to be used. IIIInnnncccclllluuuuddddeeee ddddiiiirrrreeeeccccttttiiiivvvveeeessss The include directive incorporates the contents of a specified file into a UIL module. This mechanism allows several UIL modules to share common definitions. The syntax for the include directive is as follows: IIIINNNNCCCCLLLLUUUUDDDDEEEE FFFFIIIILLLLEEEE _f_i_l_e__n_a_m_e ; The UIL compiler replaces the include directive with the contents of the include file and processes it as if these contents had appeared in the current UIL source file. You can nest include files; that is, an include file can contain include directives. The UIL compiler can process up to 100 references (including the file containing the UIL module). Therefore, you can include up to 99 files in a single UIL module, including nested files. Each time a file is opened counts as a reference, so including the same file twice counts as two references. The character expression is a file specification that identifies the file to be included. The rules for finding the specified file are similar to the rules for finding header, or ....hhhh files using the include directive, ####iiiinnnncccclllluuuuddddeeee, with a quoted string in C. The uuuuiiiillll uses the ----IIII option for specifying a search directory for include files. +o If you do not supply a directory, the UIL compiler searches for the include file in the directory of the main source file. +o If the compiler does not find the include file there, the compiler looks in the same directory as the source file. +o If you supply a directory, the UIL compiler searches only that directory for the file. LLLLAAAANNNNGGGGUUUUAAAAGGGGEEEE SSSSYYYYNNNNTTTTAAAAXXXX NNNNaaaammmmeeeessss aaaannnndddd SSSSttttrrrriiiinnnnggggssss Names can consist of any of the characters A to Z, a to z, 0 to 9, $ (dollar sign), and _ (underscore). Names cannot begin with a digit (0 to 9). The maximum length of a name Page 12 (printed 4/30/98) UUUUIIIILLLL((((5555XXXX)))) UUUUNNNNIIIIXXXX SSSSyyyysssstttteeeemmmm VVVV UUUUIIIILLLL((((5555XXXX)))) is 31 characters. UIL gives you a choice of either case-sensitive or case- insensitive names through a clause in the MMMMOOOODDDDUUUULLLLEEEE header. For example, if names are case sensitive, the names "sample" and "Sample" are distinct from each other. If names are case insensitive, these names are treated as the same name and can be used interchangeably. By default, UIL assumes names are case sensitive. In CCCCAAAASSSSEEEE----IIIINNNNSSSSEEEENNNNSSSSIIIITTTTIIIIVVVVEEEE mode, the compiler outputs all names in the UID file in uppercase form. In CCCCAAAASSSSEEEE----SSSSEEEENNNNSSSSIIIITTTTIIIIVVVVEEEE mode, names appear in the UIL file exactly as they appear in the source. The following table list the reserved keywords, which are not available for defining programmer defined names. AAAARRRRGGGGUUUUMMMMEEEENNNNTTTTSSSS CCCCAAAALLLLLLLLBBBBAAAACCCCKKKKSSSS CCCCOOOONNNNTTTTRRRROOOOLLLLSSSS EEEENNNNDDDD EEEEXXXXPPPPOOOORRRRTTTTEEEEDDDD FFFFAAAALLLLSSSSEEEE GGGGAAAADDDDGGGGEEEETTTT IIIIDDDDEEEENNNNTTTTIIIIFFFFIIIIEEEERRRR IIIINNNNCCCCLLLLUUUUDDDDEEEE LLLLIIIISSSSTTTT MMMMOOOODDDDUUUULLLLEEEE OOOOFFFFFFFF OOOONNNN OOOOBBBBJJJJEEEECCCCTTTT PPPPRRRRIIIIVVVVAAAATTTTEEEE PPPPRRRROOOOCCCCEEEEDDDDUUUURRRREEEE PPPPRRRROOOOCCCCEEEEDDDDUUUURRRREEEESSSS TTTTRRRRUUUUEEEE VVVVAAAALLLLUUUUEEEE WWWWIIIIDDDDGGGGEEEETTTT The following table list the UIL unreserved keywords. These keywords can be used as programmer defined names, however, if you use any keyword as a name, you cannot use the UIL- supplied usage of that keyword. Built-in argument names (for example: XXXXmmmmNNNNxxxx, XXXXmmmmNNNNhhhheeeeiiiigggghhhhtttt) Built-in reason names (for example: XXXXmmmmNNNNaaaaccccttttiiiivvvvaaaatttteeeeCCCCaaaallllllllbbbbaaaacccckkkk, XXXXmmmmNNNNhhhheeeellllppppCCCCaaaallllllllbbbbaaaacccckkkk) Character set names (for example: IIIISSSSOOOO____LLLLAAAATTTTIIIINNNN1111, IIIISSSSOOOO____HHHHEEEEBBBBRRRREEEEWWWW____LLLLRRRR) Constant value names (for example: XXXXmmmmMMMMEEEENNNNUUUU____OOOOPPPPTTTTIIIIOOOONNNN, XXXXmmmmBBBBRRRROOOOWWWWSSSSEEEE____SSSSEEEELLLLEEEECCCCTTTT) Object types (for example: XXXXmmmmPPPPuuuusssshhhhBBBBuuuuttttttttoooonnnn, XXXXmmmmBBBBuuuulllllllleeeettttiiiinnnnBBBBooooaaaarrrrdddd) AAAANNNNYYYY AAAARRRRGGGGUUUUMMMMEEEENNNNTTTT AAAASSSSCCCCIIIIZZZZ____SSSSTTTTRRRRIIIINNNNGGGG____TTTTAAAABBBBLLLLEEEE AAAASSSSCCCCIIIIZZZZ____TTTTAAAABBBBLLLLEEEE BBBBAAAACCCCKKKKGGGGRRRROOOOUUUUNNNNDDDD BBBBOOOOOOOOLLLLEEEEAAAANNNN CCCCAAAASSSSEEEE____IIIINNNNSSSSEEEENNNNSSSSIIIITTTTIIIIVVVVEEEE CCCCAAAASSSSEEEE____SSSSEEEENNNNSSSSIIIITTTTIIIIVVVVEEEE CCCCHHHHAAAARRRRAAAACCCCTTTTEEEERRRR____SSSSEEEETTTT CCCCOOOOLLLLOOOORRRR CCCCOOOOLLLLOOOORRRR____TTTTAAAABBBBLLLLEEEE CCCCOOOOMMMMPPPPOOOOUUUUNNNNDDDD____SSSSTTTTRRRRIIIINNNNGGGG CCCCOOOOMMMMPPPPOOOOUUUUNNNNDDDD____SSSSTTTTRRRRIIIINNNNGGGG____TTTTAAAABBBBLLLLEEEE FFFFIIIILLLLEEEE FFFFLLLLOOOOAAAATTTT FFFFOOOONNNNTTTT FFFFOOOONNNNTTTT____TTTTAAAABBBBLLLLEEEE FFFFOOOONNNNTTTTSSSSEEEETTTT FFFFOOOORRRREEEEGGGGRRRROOOOUUUUNNNNDDDD IIIICCCCOOOONNNN IIIIMMMMPPPPOOOORRRRTTTTEEEEDDDD IIIINNNNTTTTEEEEGGGGEEEERRRR IIIINNNNTTTTEEEEGGGGEEEERRRR____TTTTAAAABBBBLLLLEEEE KKKKEEEEYYYYSSSSYYYYMMMM MMMMAAAANNNNAAAAGGGGEEEEDDDD NNNNAAAAMMMMEEEESSSS OOOOBBBBJJJJEEEECCCCTTTTSSSS RRRREEEEAAAASSSSOOOONNNN RRRRGGGGBBBB RRRRIIIIGGGGHHHHTTTT____TTTTOOOO____LLLLEEEEFFFFTTTT SSSSIIIINNNNGGGGLLLLEEEE____FFFFLLLLOOOOAAAATTTT SSSSTTTTRRRRIIIINNNNGGGG SSSSTTTTRRRRIIIINNNNGGGG____TTTTAAAABBBBLLLLEEEE TTTTRRRRAAAANNNNSSSSLLLLAAAATTTTIIIIOOOONNNN____TTTTAAAABBBBLLLLEEEE UUUUNNNNMMMMAAAANNNNAAAAGGGGEEEEDDDD UUUUSSSSEEEERRRR____DDDDEEEEFFFFIIIINNNNEEEEDDDD VVVVEEEERRRRSSSSIIIIOOOONNNN WWWWIIIIDDDDEEEE____CCCCHHHHAAAARRRRAAAACCCCTTTTEEEERRRR WWWWIIIIDDDDGGGGEEEETTTT XXXXBBBBIIIITTTTMMMMAAAAPPPPFFFFIIIILLLLEEEE String literals can be composed of the upper- and lower-case letters, digits, and punctuation characters. Spaces, tabs, and comments are special elements in the language. They are Page 13 (printed 4/30/98) UUUUIIIILLLL((((5555XXXX)))) UUUUNNNNIIIIXXXX SSSSyyyysssstttteeeemmmm VVVV UUUUIIIILLLL((((5555XXXX)))) a means of delimiting other elements, such as two names. One or more of these elements can appear before or after any other element in the language. However, spaces, tabs, and comments that appear in string literals are treated as character sequences rather than delimiters. DDDDaaaattttaaaa TTTTyyyyppppeeeessss UIL provides literals for several of the value types it supports. Some of the value types are not supported as literals (for example, pixmaps and string tables). You can specify values for these types by using functions described in the _F_u_n_c_t_i_o_n_s section. UIL directly supports the following literal types: +o String literal +o Integer literal +o Boolean literal +o Floating-point literal UIL also includes the data type AAAANNNNYYYY, which is used to turn off compile time checking of data types. SSSSttttrrrriiiinnnngggg LLLLiiiitttteeeerrrraaaallllssss A string literal is a sequence of zero or more 8-bit or 16- bit characters or a combination delimited by '''' (single quotation marks) or """" (double quotation marks). String literals can also contain multibyte characters delimited with double quotation marks. String literals can be no more than 2000 characters long. A single-quoted string literal can span multiple source lines. To continue a single-quoted string literal, terminate the continued line with a \\\\ (backslash). The literal continues with the first character on the next line. Double-quoted string literals cannot span multiple source lines. (Because double-quoted strings can contain escape sequences and other special characters, you cannot use the backslash character to designate continuation of the string.) To build a string value that must span multiple source lines, use the concatenation operator described later in this section. The syntax of a string literal is one of the following: ''''[_c_h_a_r_a_c_t_e_r__s_t_r_i_n_g]'''' [####_c_h_a_r__s_e_t]""""[_c_h_a_r_a_c_t_e_r__s_t_r_i_n_g]"""" Page 14 (printed 4/30/98) UUUUIIIILLLL((((5555XXXX)))) UUUUNNNNIIIIXXXX SSSSyyyysssstttteeeemmmm VVVV UUUUIIIILLLL((((5555XXXX)))) Both string forms associate a character set with a string value. UIL uses the following rules to determine the character set and storage format for string literals: +o A string declared as ''''_s_t_r_i_n_g'''' is equivalent to ####_c_u_r__c_h_a_r_s_e_t""""_s_t_r_i_n_g"""", where _c_u_r__c_h_a_r_s_e_t will be the codeset portion of the value of the LLLLAAAANNNNGGGG environment variable if it is set or the value of XXXXmmmmFFFFAAAALLLLLLLLBBBBAAAACCCCKKKK____CCCCHHHHAAAARRRRSSSSEEEETTTT if LLLLAAAANNNNGGGG is not set or has no codeset component. By default XXXXmmmmFFFFAAAALLLLLLLLBBBBAAAACCCCKKKK____CCCCHHHHAAAARRRRSSSSEEEETTTT is IIIISSSSOOOO8888888855559999----1111 (equivalent to IIIISSSSOOOO____LLLLAAAATTTTIIIINNNN1111), but vendors may define a different default. +o A string declared as """"_s_t_r_i_n_g"""" is equivalent to ####_c_h_a_r__s_e_t""""_s_t_r_i_n_g"""" if you specified _c_h_a_r__s_e_t as the default character set for the module. If no default character set has been specified for the module, then if the ----ssss option is provided to the uuuuiiiillll command or the uuuusssseeee____sssseeeettttllllooooccccaaaalllleeee____ffffllllaaaagggg is set for the callable compiler, UUUUiiiillll(((()))), the string will be interpreted to be a string in the current locale. This means that the string is parsed in the locale of the user by calling sssseeeettttllllooooccccaaaalllleeee and its charset is XXXXmmmmFFFFOOOONNNNTTTTLLLLIIIISSSSTTTT____DDDDEEEEFFFFAAAAUUUULLLLTTTT____TTTTAAAAGGGG, and that if the string is converted to a compound string, it is stored as a locale encoded text segment. Otherwise, """"_s_t_r_i_n_g"""" is equivalent to ####_c_u_r__c_h_a_r_s_e_t""""_s_t_r_i_n_g"""", where _c_u_r__c_h_a_r_s_e_t is interpreted as described for single quoted strings. +o A string of the form """"_s_t_r_i_n_g"""" or ####_c_h_a_r__s_e_t""""_s_t_r_i_n_g"""" is stored as a null-terminated string. The following table lists the character sets supported by the UIL compiler for string literals. Note that several UIL names map to the same character set. In some cases, the UIL name influences how string literals are read. For example, strings identified by a UIL character set name ending in _LR are read left-to-right. Names that end in a different number reflect different fonts (for example, ISO_LATIN1 or ISO_LATIN6). All character sets in this table are represented by 8 bits. UUUUIIIILLLL NNNNaaaammmmeeee DDDDeeeessssccccrrrriiiippppttttiiiioooonnnn IIIISSSSOOOO____LLLLAAAATTTTIIIINNNN1111 GL: ASCII, GR: Latin-1 Supplement IIIISSSSOOOO____LLLLAAAATTTTIIIINNNN2222 GL: ASCII, GR: Latin-2 Supplement IIIISSSSOOOO____AAAARRRRAAAABBBBIIIICCCC GL: ASCII, GR: Latin-Arabic Supplement IIIISSSSOOOO____LLLLAAAATTTTIIIINNNN6666 GL: ASCII, GR: Latin-Arabic Supplement IIIISSSSOOOO____GGGGRRRREEEEEEEEKKKK GL: ASCII, GR: Latin-Greek Supplement Page 15 (printed 4/30/98) UUUUIIIILLLL((((5555XXXX)))) UUUUNNNNIIIIXXXX SSSSyyyysssstttteeeemmmm VVVV UUUUIIIILLLL((((5555XXXX)))) IIIISSSSOOOO____LLLLAAAATTTTIIIINNNN7777 GL: ASCII, GR: Latin-Greek Supplement IIIISSSSOOOO____HHHHEEEEBBBBRRRREEEEWWWW GL: ASCII, GR: Latin-Hebrew Supplement IIIISSSSOOOO____LLLLAAAATTTTIIIINNNN8888 GL: ASCII, GR: Latin-Hebrew Supplement IIIISSSSOOOO____HHHHEEEEBBBBRRRREEEEWWWW____LLLLRRRR GL: ASCII, GR: Latin-Hebrew Supplement IIIISSSSOOOO____LLLLAAAATTTTIIIINNNN8888____LLLLRRRR GL: ASCII, GR: Latin-Hebrew Supplement JJJJIIIISSSS____KKKKAAAATTTTAAAAKKKKAAAANNNNAAAA GL: JIS Roman, GR: JIS Katakana Following are the parsing rules for each of the character sets: All character sets Character codes in the range 00...1F, 7F, and 80...9F are control characters including both bytes of 16-bit characters. The compiler flags these as illegal characters. IIIISSSSOOOO____LLLLAAAATTTTIIIINNNN1111 IIIISSSSOOOO____LLLLAAAATTTTIIIINNNN2222 IIIISSSSOOOO____AAAARRRRAAAABBBBIIIICCCC IIIISSSSOOOO____LLLLAAAATTTTIIIINNNN3333 IIIISSSSOOOO____GGGGRRRREEEEEEEEKKKK IIIISSSSOOOO____LLLLAAAATTTTIIIINNNN4444 These sets are parsed from left to right. The escape sequences for null-terminated strings are also supported by these character sets. IIIISSSSOOOO____HHHHEEEEBBBBRRRREEEEWWWW IIIISSSSOOOO____LLLLAAAATTTTIIIINNNN8888 These sets are parsed from right to left; for example, the string ####IIIISSSSOOOO____HHHHEEEEBBBBRRRREEEEWWWW""""000011112222333344445555"""" generates a primitive string "543210" with character set IIIISSSSOOOO____HHHHEEEEBBBBRRRREEEEWWWW. A DDIS descriptor for such a string has this segment marked as being right_to_left. The escape sequences for null- terminated strings are also supported by these character sets, and the characters that compose the escape sequences are in left-to-right order. For example, you type \n, not n\. IIIISSSSOOOO____HHHHEEEEBBBBRRRREEEEWWWW____LLLLRRRR IIIISSSSOOOO____LLLLAAAATTTTIIIINNNN8888____LLLLRRRR These sets are parsed from left to right; for example, the string ####IIIISSSSOOOO____HHHHEEEEBBBBRRRREEEEWWWW____LLLLRRRR""""000011112222333344445555"""" generates a primitive string "012345" with character set IIIISSSSOOOO____HHHHEEEEBBBBRRRREEEEWWWW. A DDIS descriptor for such a string marks this segment as being left_to_right. The escape sequences for null- terminated strings are also supported by these character sets. JJJJIIIISSSS____KKKKAAAATTTTAAAAKKKKAAAANNNNAAAA This set is parsed from left to right. The escape sequences for null-terminated strings are also supported by this character set. Note that the \\\\ (backslash) may be displayed as a yen symbol. In addition to designating parsing rules for strings, character set information remains an attribute of a compound Page 16 (printed 4/30/98) UUUUIIIILLLL((((5555XXXX)))) UUUUNNNNIIIIXXXX SSSSyyyysssstttteeeemmmm VVVV UUUUIIIILLLL((((5555XXXX)))) string. If the string is included in a string consisting of several concatenated segments, the character set information is included with that string segment. This gives the Motif Toolkit the information it needs to decipher the compound string and choose a font to display the string. For an application interface displayed only in English, UIL lets you ignore the distinctions between the two uses of strings. The compiler recognizes by context when a string must be passed as a null-terminated string or as a compound string. The UIL compiler recognizes enough about the various character sets to correctly parse string literals. The compiler also issues errors if you use a compound string in a context that supports only null-terminated strings. Since the character set names are keywords, you must put them in lowercase if case-sensitive names are in force. If names are case insensitive, character set names can be uppercase, lowercase, or mixed case. In addition to the built-in character sets recognized by UIL, you can define your own character sets with the CCCCHHHHAAAARRRRAAAACCCCTTTTEEEERRRR____SSSSEEEETTTT function. You can use the CCCCHHHHAAAARRRRAAAACCCCTTTTEEEERRRR____SSSSEEEETTTT function anywhere a character set can be specified. String literals can contain characters with the eighth (high-order) bit set. You cannot type control characters (00..1F, 7F, and 80..9F) directly in a single-quoted string literal. However, you can represent these characters with escape sequences. The following list shows the escape sequences for special characters. \\\\bbbb Backspace \\\\ffff Form-feed \\\\nnnn Newline \\\\rrrr Carriage return \\\\tttt Horizontal tab \\\\vvvv Vertical tab \\\\'''' Single quotation mark \\\\"""" Double quotation mark \\\\\\\\ Backslash Page 17 (printed 4/30/98) UUUUIIIILLLL((((5555XXXX)))) UUUUNNNNIIIIXXXX SSSSyyyysssstttteeeemmmm VVVV UUUUIIIILLLL((((5555XXXX)))) \\\\_i_n_t_e_g_e_r\\\\ Character whose internal representation is given by _i_n_t_e_g_e_r (in the range 0 to 255 decimal) Note that escape sequences are processed literally in strings that are parsed in the current locale (localized strings). The UIL compiler does not process newline characters in compound strings. The effect of a newline character in a compound string depends only on the character set of the string, and the result is not guaranteed to be a multiline string. CCCCoooommmmppppoooouuuunnnndddd SSSSttttrrrriiiinnnngggg LLLLiiiitttteeeerrrraaaallllssss A compound string consists of a string of 8-bit, 16-bit, or multibyte characters, a named character set, and a writing direction. Its UIL data type is ccccoooommmmppppoooouuuunnnndddd____ssssttttrrrriiiinnnngggg. The writing direction of a compound string is implied by the character set specified for the string. You can explicitly set the writing direction for a compound string by using the CCCCOOOOMMMMPPPPOOOOUUUUNNNNDDDD____SSSSTTTTRRRRIIIINNNNGGGG function. A compound string can consist of a sequence of concatenated compound strings, null-terminated strings, or a combination of both, each of which can have a different character set property and writing direction. Use the concatenation operator &&&& (ampersand) to create a sequence of compound strings. Each string in the sequence is stored, including the character set and writing direction information. Generally, a string literal is stored in the UID file as a compound string when the literal consists of concatenated strings having different character sets or writing directions, or when you use the string to specify a value for an argument that requires a compound string value. If you want to guarantee that a string literal is stored as a compound string, you must use the CCCCOOOOMMMMPPPPOOOOUUUUNNNNDDDD____SSSSTTTTRRRRIIIINNNNGGGG function. DDDDaaaattttaaaa SSSSttttoooorrrraaaaggggeeee CCCCoooonnnnssssuuuummmmppppttttiiiioooonnnn ffffoooorrrr SSSSttttrrrriiiinnnngggg LLLLiiiitttteeeerrrraaaallllssss The way a string literal is stored in the UID file depends on how you declare and use the string. The UIL compiler automatically converts a null-terminated string to a compound string if you use the string to specify the value of an argument that requires a compound string. However, this conversion is costly in terms of storage consumption. Page 18 (printed 4/30/98) UUUUIIIILLLL((((5555XXXX)))) UUUUNNNNIIIIXXXX SSSSyyyysssstttteeeemmmm VVVV UUUUIIIILLLL((((5555XXXX)))) PPPPRRRRIIIIVVVVAAAATTTTEEEE, EEEEXXXXPPPPOOOORRRRTTTTEEEEDDDD, and IIIIMMMMPPPPOOOORRRRTTTTEEEEDDDD string literals require storage for a single allocation when the literal is declared; thereafter, storage is required for each reference to the literal. Literals declared in-line require storage for both an allocation and a reference. The following table summarizes data storage consumption for string literals. The storage requirement for an allocation consists of a fixed portion and a variable portion. The fixed portion of an allocation is roughly the same as the storage requirement for a reference (a few bytes). The storage consumed by the variable portion depends on the size of the literal value (that is, the length of the string). To conserve storage space, avoid making string literal declarations that result in an allocation per use. SSSSttttoooorrrraaaaggggeeee RRRReeeeqqqquuuuiiiirrrreeeemmmmeeeennnnttttssss DDDDeeeeccccllllaaaarrrraaaattttiiiioooonnnn DDDDaaaattttaaaa TTTTyyyyppppeeee UUUUsssseeeedddd AAAAssss PPPPeeeerrrr UUUUsssseeee In-line Null-terminated Null-terminated An allocation and a reference (within the module) Private Null-terminated Null-terminated A reference (within the module) Exported Null-terminated Null-terminated A reference (within the UID hierarchy) Imported Null-terminated Null-terminated A reference (within the UID hierarchy) In-line Null-terminated Compound An allocation and a reference (within the module) Private Null-terminated Compound An allocation and a reference (within the module) Exported Null-terminated Compound A reference (within the UID hierarchy) Imported Null-terminated Compound A reference (within the UID hierarchy) In-line Compound Compound An allocation and a reference (within the module) Private Compound Compound A reference (within the module) Exported Compound Compound A reference (within the UID hierarchy) Imported Compound Compound A reference (within the UID hierarchy) IIIInnnntttteeeeggggeeeerrrr LLLLiiiitttteeeerrrraaaallllssss An integer literal represents the value of a whole number. Integer literals have the form of an optional sign followed by one or more decimal digits. An integer literal must not contain embedded spaces or commas. Page 19 (printed 4/30/98) UUUUIIIILLLL((((5555XXXX)))) UUUUNNNNIIIIXXXX SSSSyyyysssstttteeeemmmm VVVV UUUUIIIILLLL((((5555XXXX)))) Integer literals are stored in the UID file as long integers. Exported and imported integer literals require a single allocation when the literal is declared; thereafter, a few bytes of storage are required for each reference to the literal. Private integer literals and those declared in-line require allocation and reference storage per use. To conserve storage space, avoid making integer literal declarations that result in an allocation per use. The following table shows data storage consumption for integer literals. DDDDeeeeccccllllaaaarrrraaaattttiiiioooonnnn SSSSttttoooorrrraaaaggggeeee RRRReeeeqqqquuuuiiiirrrreeeemmmmeeeennnnttttssss PPPPeeeerrrr UUUUsssseeee In-line An allocation and a reference (within the module) Private An allocation and a reference (within the module) Exported A reference (within the UID hierarchy) Imported A reference (within the UID hierarchy) BBBBoooooooolllleeeeaaaannnn LLLLiiiitttteeeerrrraaaallll A Boolean literal represents the value True (reserved keyword TTTTRRRRUUUUEEEE or OOOOnnnn) or False (reserved keyword FFFFAAAALLLLSSSSEEEE or OOOOffffffff). These keywords are subject to case-sensitivity rules. In a UID file, TTTTRRRRUUUUEEEE is represented by the integer value 1 and FFFFAAAALLLLSSSSEEEE is represented by the integer value 0. Data storage consumption for Boolean literals is the same as that for integer literals. FFFFllllooooaaaattttiiiinnnngggg----PPPPooooiiiinnnntttt LLLLiiiitttteeeerrrraaaallll A floating-point literal represents the value of a real (or float) number. Floating-point literals have the following form: [++++|----][_i_n_t_e_g_e_r]...._i_n_t_e_g_e_r[EEEE|eeee[++++|----]_e_x_p_o_n_e_n_t] For maximum portability a floating-point literal can represent values in the range 1.0E-37 to 1.0E+37 with at least 6 significant digits. On many machines this range will be wider, with more significant digits. A floating- point literal must not contain embedded spaces or commas. Floating-point literals are stored in the UID file as double-precision, floating-point numbers. The following table gives examples of valid and invalid floating-point notation for the UIL compiler. VVVVaaaalllliiiidddd FFFFllllooooaaaattttiiiinnnngggg----PPPPooooiiiinnnntttt LLLLiiiitttteeeerrrraaaallllssss IIIInnnnvvvvaaaalllliiiidddd FFFFllllooooaaaattttiiiinnnngggg----PPPPooooiiiinnnntttt LLLLiiiitttteeeerrrraaaallllssss 1.0 1e1 (no decimal point) .1 E-1 (no decimal point or digits) Page 20 (printed 4/30/98) UUUUIIIILLLL((((5555XXXX)))) UUUUNNNNIIIIXXXX SSSSyyyysssstttteeeemmmm VVVV UUUUIIIILLLL((((5555XXXX)))) 3.1415E-2 (equals .031415) 2.87 e6 (embedded blanks) -6.29e7 (equals -62900000) 2.0e100 (out of range) Data storage consumption for floating-point literals is the same as that for integer literals. TTTThhhheeee AAAANNNNYYYY DDDDaaaattttaaaa TTTTyyyyppppeeee The purpose of the AAAANNNNYYYY data type is to shut off the data- type checking feature of the UIL compiler. You can use the AAAANNNNYYYY data type for the following: +o Specifying the type of a callback procedure tag +o Specifying the type of a user-defined argument You can use the AAAANNNNYYYY data type when you need to use a type not supported by the UIL compiler or when you want the data-type restrictions imposed by the compiler to be relaxed. For example, you might want to define a widget having an argument that can accept different types of values, depending on run-time circumstances. If you specify that an argument takes an AAAANNNNYYYY value, the compiler does not check the type of the value specified for that argument; therefore, you need to take care when specifying a value for an argument of type AAAANNNNYYYY. You could get unexpected results at run time if you pass a value having a data type that the widget does not support for that argument. EEEExxxxpppprrrreeeessssssssiiiioooonnnnssss UIL includes compile-time value expressions. These expressions can contain references to other UIL values, but cannot be forward referenced. The following table lists the set of operators in UIL that allow you to create integer, real, and Boolean values based on other values defined with the UIL module. In the table, a precedence of 1 is the highest. OOOOppppeeeerrrraaaattttoooorrrr OOOOppppeeeerrrraaaannnndddd TTTTyyyyppppeeeessss MMMMeeeeaaaannnniiiinnnngggg PPPPrrrreeeecccceeeeddddeeeennnncccceeee ~~~~ Boolean NOT 1 integer One's complement ---- float Negate 1 integer Negate ++++ float NOP 1 integer NOP **** float,float Multiply 2 Page 21 (printed 4/30/98) UUUUIIIILLLL((((5555XXXX)))) UUUUNNNNIIIIXXXX SSSSyyyysssstttteeeemmmm VVVV UUUUIIIILLLL((((5555XXXX)))) integer,integer Multiply //// float,float Divide 2 integer,integer Divide ++++ float,float Add 3 integer,integer Add ---- float,float Subtract 3 integer,integer Subtract >>>>>>>> integer,integer Shift right 4 <<<<<<<< integer,integer Shift left 4 &&&& Boolean,Boolean AND 5 integer,integer Bitwise AND string,string Concatenate |||| Boolean,Boolean OR 6 integer,integer Bitwise OR ^^^^ Boolean,Boolean XOR 6 integer,integer Bitwise XOR A string can be either a single compound string or a sequence of compound strings. If the two concatenated strings have different properties (such as writing direction or character set), the result of the concatenation is a multisegment compound string. The string resulting from the concatenation is a null- terminated string unless one or more of the following conditions exists: +o One of the operands is a compound string +o The operands have different character set properties +o The operands have different writing directions Then the resulting string is a compound string. You cannot use imported or exported values as operands of the concatenation operator. The result of each operator has the same type as its operands. You cannot mix types in an expression without using conversion routines. You can use parentheses to override the normal precedence of operators. In a sequence of unary operators, the operations are performed in right-to-left order. For example, ---- ++++ ----AAAA is equivalent to ----((((++++((((----AAAA)))))))). In a sequence of binary operators of the same precedence, the operations are performed in left-to-right order. For example, AAAA****BBBB////CCCC****DDDD is equivalent to ((((((((AAAA****BBBB))))////CCCC))))****DDDD. A value declaration gives a value a name. You cannot Page 22 (printed 4/30/98) UUUUIIIILLLL((((5555XXXX)))) UUUUNNNNIIIIXXXX SSSSyyyysssstttteeeemmmm VVVV UUUUIIIILLLL((((5555XXXX)))) redefine the value of that name in a subsequent value declaration. You can use a value containing operators and functions anywhere you can use a value in a UIL module. You cannot use imported values as operands in expressions. Several of the binary operators are defined for multiple data types. For example, the operator for multiplication (****) is defined for both floating-point and integer operands. For the UIL compiler to perform these binary operations, both operands must be of the same type. If you supply operands of different data types, the UIL compiler automatically converts one of the operands to the type of the other according to the following conversions rules. +o If the operands are an integer and a boolean, the boolean is converted to an integer. +o If the operands are an integer and a floating-point, the integer is converted to an floating-point. +o If the operands are a floating-point and a boolean, the boolean is converted to a floating-point. You can also explicitly convert the data type of a value by using one of the conversion functions IIIINNNNTTTTEEEEGGGGEEEERRRR, FFFFLLLLOOOOAAAATTTT or SSSSIIIINNNNGGGGLLLLEEEE____FFFFLLLLOOOOAAAATTTT. FFFFuuuunnnnccccttttiiiioooonnnnssss UIL provides functions to generate the following types of values: +o Character sets +o Keysyms +o Colors +o Pixmaps +o Single-precision, floating-point numbers +o Double-precision, floating-point numbers +o Fonts +o Fontsets +o Font tables Page 23 (printed 4/30/98) UUUUIIIILLLL((((5555XXXX)))) UUUUNNNNIIIIXXXX SSSSyyyysssstttteeeemmmm VVVV UUUUIIIILLLL((((5555XXXX)))) +o Compound strings +o Compound string tables +o ASCIZ (null-terminated) string tables +o Wide character strings +o Widget class names +o Integer tables +o Arguments +o Reasons +o Translation tables Remember that all examples in the following sections assume case-insensitive mode. Keywords are shown in uppercase letters to distinguish them from user-specified names, which are shown in lowercase letters. This use of uppercase letters is not required in case-insensitive mode. In case- sensitive mode, keywords must be in lowercase letters. CCCCHHHHAAAARRRRAAAACCCCTTTTEEEERRRR____SSSSEEEETTTT((((_s_t_r_i_n_g__e_x_p_r_e_s_s_i_o_n[,,,, property[,,,, ...]])))) You can define your own character sets with the CCCCHHHHAAAARRRRAAAACCCCTTTTEEEERRRR____SSSSEEEETTTT function. You can use the CCCCHHHHAAAARRRRAAAACCCCTTTTEEEERRRR____SSSSEEEETTTT function anywhere a character set can be specified. The result of the CCCCHHHHAAAARRRRAAAACCCCTTTTEEEERRRR____SSSSEEEETTTT function is a character set with the name _s_t_r_i_n_g__e_x_p_r_e_s_s_i_o_n and the properties you specify. _S_t_r_i_n_g__e_x_p_r_e_s_s_i_o_n must be a null- terminated string. You can optionally include one or both of the following clauses to specify properties for the resulting character set: RRRRIIIIGGGGHHHHTTTT____TTTTOOOO____LLLLEEEEFFFFTTTT ==== _b_o_o_l_e_a_n__e_x_p_r_e_s_s_i_o_n SSSSIIIIXXXXTTTTEEEEEEEENNNN____BBBBIIIITTTT ==== _b_o_o_l_e_a_n__e_x_p_r_e_s_s_i_o_n The RRRRIIIIGGGGHHHHTTTT____TTTTOOOO____LLLLEEEEFFFFTTTT clause sets the default writing direction of the string from right to left if _b_o_o_l_e_a_n__e_x_p_r_e_s_s_i_o_n is True, and right to left otherwise. The SSSSIIIIXXXXTTTTEEEEEEEENNNN____BBBBIIIITTTT clause allows the strings associated with this character set to be interpreted as 16-bit characters if _b_o_o_l_e_a_n__e_x_p_r_e_s_s_i_o_n is True, and 8-bit characters otherwise. Page 24 (printed 4/30/98) UUUUIIIILLLL((((5555XXXX)))) UUUUNNNNIIIIXXXX SSSSyyyysssstttteeeemmmm VVVV UUUUIIIILLLL((((5555XXXX)))) KKKKEEEEYYYYSSSSYYYYMMMM((((_s_t_r_i_n_g__l_i_t_e_r_a_l)))) The KKKKEEEEYYYYSSSSYYYYMMMM function is used to specify a keysym for a mnemonic resource. The _s_t_r_i_n_g__l_i_t_e_r_a_l must contain exactly one character. CCCCOOOOLLLLOOOORRRR((((_s_t_r_i_n_g__e_x_p_r_e_s_s_i_o_n[,,,,FFFFOOOORRRREEEEGGGGRRRROOOOUUUUNNNNDDDD|BBBBAAAACCCCKKKKGGGGRRRROOOOUUUUNNNNDDDD])))) The CCCCOOOOLLLLOOOORRRR function supports the definition of colors. Using the CCCCOOOOLLLLOOOORRRR function, you can designate a value to specify a color and then use that value for arguments requiring a color value. The string expression names the color you want to define; the optional keywords FFFFOOOORRRREEEEGGGGRRRROOOOUUUUNNNNDDDD and BBBBAAAACCCCKKKKGGGGRRRROOOOUUUUNNNNDDDD identify how the color is to be displayed on a monochrome device when the color is used in the definition of a color table. The UIL compiler does not have built-in color names. Colors are a server-dependent attribute of an object. Colors are defined on each server and may have different red-green-blue (RGB) values on each server. The string you specify as the color argument must be recognized by the server on which your application runs. In a UID file, UIL represents a color as a character string. MRM calls X translation routines that convert a color string to the device-specific pixel value. If you are running on a monochrome server, all colors translate to black or white. If you are on a color server, the color names translate to their proper colors if the following conditions are met: +o The color is defined. +o The color map is not yet full. If the color map is full, even valid colors translate to black or white (foreground or background). Interfaces do not, in general, specify colors for widgets, so that the selection of colors can be controlled by the user through the ....XXXXddddeeeeffffaaaauuuullllttttssss file. To write an application that runs on both monochrome and color devices, you need to specify which colors in a color table (defined with the CCCCOOOOLLLLOOOORRRR____TTTTAAAABBBBLLLLEEEE function) map to the background and which colors map to the foreground. UIL lets you use the CCCCOOOOLLLLOOOORRRR function to designate this mapping in the definition of the color. The following example shows how to use the CCCCOOOOLLLLOOOORRRR function to map the color red to the background color Page 25 (printed 4/30/98) UUUUIIIILLLL((((5555XXXX)))) UUUUNNNNIIIIXXXX SSSSyyyysssstttteeeemmmm VVVV UUUUIIIILLLL((((5555XXXX)))) on a monochrome device: VALUE c: COLOR ( 'red',BACKGROUND ); The mapping comes into play only when the MRM is given a color and the application is to be displayed on a monochrome device. In this case, each color is considered to be in one of the following three categories: +o The color is mapped to the background color on the monochrome device. +o The color is mapped to the foreground color on the monochrome device. +o Monochrome mapping is undefined for this color. If the color is mapped to the foreground or background color, MRM substitutes the foreground or background color, respectively. If you do not specify the monochrome mapping for a color, MRM passes the color string to the Motif Toolkit for mapping to the foreground or background color. RRRRGGGGBBBB((((_r_e_d__i_n_t_e_g_e_r,,,, _g_r_e_e_n__i_n_t_e_g_e_r,,,, _b_l_u_e__i_n_t_e_g_e_r)))) The three integers define the values for the red, green, and blue components of the color, in that order. The values of these components can range from 0 to 65,535, inclusive. In a UID file, UIL represents an RRRRGGGGBBBB value as three integers. MRM calls X translation routines that convert the integers to the device-specific pixel value. If you are running on a monochrome server, all colors translate to black or white. If you are on a color server, RRRRGGGGBBBB values translate to their proper colors if the colormap is not yet full. If the colormap is full, values translate to black or white (foreground or background). CCCCOOOOLLLLOOOORRRR____TTTTAAAABBBBLLLLEEEE((((_c_o_l_o_r__e_x_p_r_e_s_s_i_o_n====''''_c_h_a_r_a_c_t_e_r''''[,,,,...])))) The color expression is a previously defined color, a color defined in line with the CCCCOOOOLLLLOOOORRRR function, or the phrase BBBBAAAACCCCKKKKGGGGRRRROOOOUUUUNNNNDDDD CCCCOOOOLLLLOOOORRRR or FFFFOOOORRRREEEEGGGGRRRROOOOUUUUNNNNDDDD CCCCOOOOLLLLOOOORRRR. The character can be any valid UIL character. The CCCCOOOOLLLLOOOORRRR____TTTTAAAABBBBLLLLEEEE function provides a device-independent way to specify a set of colors. The CCCCOOOOLLLLOOOORRRR____TTTTAAAABBBBLLLLEEEE function accepts either previously defined UIL color Page 26 (printed 4/30/98) UUUUIIIILLLL((((5555XXXX)))) UUUUNNNNIIIIXXXX SSSSyyyysssstttteeeemmmm VVVV UUUUIIIILLLL((((5555XXXX)))) names or in line color definitions (using the CCCCOOOOLLLLOOOORRRR function). A color table must be private because its contents must be known by the UIL compiler to construct an icon. The colors within a color table, however, can be imported, exported, or private. The single letter associated with each color is the character you use to represent that color when creating an icon. Each letter used to represent a color must be unique within the color table. IIIICCCCOOOONNNN(((([CCCCOOOOLLLLOOOORRRR____TTTTAAAABBBBLLLLEEEE====_c_o_l_o_r__t_a_b_l_e__n_a_m_e,,,,] _r_o_w[,,,,...)))) The color table name must refer to a previously defined color table and the row is a character expression giving one row of the icon. The IIIICCCCOOOONNNN function describes a rectangular icon that is x pixels wide and y pixels high. The strings surrounded by single quotation marks describe the icon. Each string represents a row in the icon; each character in the string represents a pixel. The first row in an icon definition determines the width of the icon. All rows must have the same number of characters as the first row. The height of the icon is dictated by the number of rows. The first argument of the IIIICCCCOOOONNNN function (the color table specification) is optional and identifies the colors that are available in this icon. By using the single letter associated with each color, you can specify the color of each pixel in the icon. The icon must be constructed of characters defined in the specified color table. A default color table is used if you omit the argument specifying the color table. To make use of the default color table, the rows of your icon must contain only spaces and asterisks. The default color table is defined as follows: COLOR_TABLE( BACKGROUND COLOR = ' ', FOREGROUND COLOR = '*' ) You can define other characters to represent the background color and foreground color by replacing the space and asterisk in the BBBBAAAACCCCKKKKGGGGRRRROOOOUUUUNNNNDDDD CCCCOOOOLLLLOOOORRRR and FFFFOOOORRRREEEEGGGGRRRROOOOUUUUNNNNDDDD CCCCOOOOLLLLOOOORRRR clauses shown in the previous statement. You can specify icons as private, imported, or exported. Use the MRM function MMMMrrrrmmmmFFFFeeeettttcccchhhhIIIIccccoooonnnnLLLLiiiitttteeeerrrraaaallll to retrieve an exported icon at run time. Page 27 (printed 4/30/98) UUUUIIIILLLL((((5555XXXX)))) UUUUNNNNIIIIXXXX SSSSyyyysssstttteeeemmmm VVVV UUUUIIIILLLL((((5555XXXX)))) XXXXBBBBIIIITTTTMMMMAAAAPPPPFFFFIIIILLLLEEEE((((_s_t_r_i_n_g__e_x_p_r_e_s_s_i_o_n)))) The XXXXBBBBIIIITTTTMMMMAAAAPPPPFFFFIIIILLLLEEEE function is similar to the IIIICCCCOOOONNNN function in that both describe a rectangular icon that is x pixels wide and y pixels high. However, XXXXBBBBIIIITTTTMMMMAAAAPPPPFFFFIIIILLLLEEEE allows you to specify an external file containing the definition of an X bitmap, whereas all IIIICCCCOOOONNNN function definitions must be coded directly within UIL. X bitmap files can be generated by many different X applications. UIL reads these files through the XXXXBBBBIIIITTTTMMMMAAAAPPPPFFFFIIIILLLLEEEE function, but does not support creation of these files. The X bitmap file specified as the argument to the XXXXBBBBIIIITTTTMMMMAAAAPPPPFFFFIIIILLLLEEEE function is read at application run time by MRM. The XXXXBBBBIIIITTTTMMMMAAAAPPPPFFFFIIIILLLLEEEE function returns a value of type ppppiiiixxxxmmmmaaaapppp and can be used anywhere a pixmap data type is expected. SSSSIIIINNNNGGGGLLLLEEEE____FFFFLLLLOOOOAAAATTTT((((_r_e_a_l__n_u_m_b_e_r__l_i_t_e_r_a_l)))) The SSSSIIIINNNNGGGGLLLLEEEE____FFFFLLLLOOOOAAAATTTT function lets you store floating-point literals in UIL files as single-precision, floating- point numbers. Single-precision floating-point numbers can often be stored using less memory than double- precision, floating-point numbers. The _r_e_a_l__n_u_m_b_e_r__l_i_t_e_r_a_l can be either an integer literal or a floating-point literal. A value defined using this function cannot be used in an arithmetic expression. FFFFLLLLOOOOAAAATTTT((((_r_e_a_l__n_u_m_b_e_r__l_i_t_e_r_a_l)))) The FFFFLLLLOOOOAAAATTTT function lets you store floating-point literals in UIL files as double-precision, floating- point numbers. The _r_e_a_l__n_u_m_b_e_r__l_i_t_e_r_a_l can be either an integer literal or a floating-point literal. FFFFOOOONNNNTTTT((((_s_t_r_i_n_g__e_x_p_r_e_s_s_i_o_n[,,,, CCCCHHHHAAAARRRRAAAACCCCTTTTEEEERRRR____SSSSEEEETTTT====_c_h_a_r__s_e_t])))) You define fonts with the FFFFOOOONNNNTTTT function. Using the FFFFOOOONNNNTTTT function, you designate a value to specify a font and then use that value for arguments that require a font value. The UIL compiler has no built-in fonts. Each font makes sense only in the context of a character set. The FFFFOOOONNNNTTTT function has an additional parameter to let you specify the character set for the font. This parameter is optional; if you omit it, the default character set depends on the value of the LLLLAAAANNNNGGGG environment variable if it is set of the value of XXXXmmmmFFFFAAAALLLLLLLLBBBBAAAACCCCKKKK____CCCCHHHHAAAARRRRSSSSEEEETTTT if LLLLAAAANNNNGGGG is not set. The string expression specifies the name of the font and the clause CCCCHHHHAAAARRRRAAAACCCCTTTTEEEERRRR____SSSSEEEETTTT = _c_h_a_r__s_e_t specifies the character set for the font. The string expression used in the FFFFOOOONNNNTTTT function cannot be a compound string. Page 28 (printed 4/30/98) UUUUIIIILLLL((((5555XXXX)))) UUUUNNNNIIIIXXXX SSSSyyyysssstttteeeemmmm VVVV UUUUIIIILLLL((((5555XXXX)))) FFFFOOOONNNNTTTTSSSSEEEETTTT((((_s_t_r_i_n_g__e_x_p_r_e_s_s_i_o_n[,,,,...][,,,, CCCCHHHHAAAARRRRAAAACCCCTTTTEEEERRRR____SSSSEEEETTTT====_c_h_a_r_s_e_t])))) You define fontsets with the FFFFOOOONNNNTTTTSSSSEEEETTTT function. Using the FFFFOOOONNNNTTTTSSSSEEEETTTT function, you designate a set of values to specify fonts and then use those values for arguments that require a fontset. The UIL compiler has no built-in fonts. Each font makes sense only in the context of a character set. The FFFFOOOONNNNTTTTSSSSEEEETTTT function has an additional parameter to let you specify the character set for the font. This parameter is optional; if you omit it, the default character set depends on the value of the LLLLAAAANNNNGGGG environment variable if it is set of the value of XXXXmmmmFFFFAAAALLLLLLLLBBBBAAAACCCCKKKK____CCCCHHHHAAAARRRRSSSSEEEETTTT if LLLLAAAANNNNGGGG is not set. The string expression specifies the name of the font and the clause CCCCHHHHAAAARRRRAAAACCCCTTTTEEEERRRR____SSSSEEEETTTT = _c_h_a_r__s_e_t specifies the character set for the font. The string expression used in the FFFFOOOONNNNTTTTSSSSEEEETTTT function cannot be a compound string. FFFFOOOONNNNTTTT____TTTTAAAABBBBLLLLEEEE((((_f_o_n_t__e_x_p_r_e_s_s_i_o_n[,,,,...])))) A font table is a sequence of pairs of fonts and character sets. At run time when an object needs to display a string, the object scans the font table for the character set that matches the character set of the string to be displayed. UIL provides the FFFFOOOONNNNTTTT____TTTTAAAABBBBLLLLEEEE function to let you supply such an argument. The font expression is created with the FFFFOOOONNNNTTTT and FFFFOOOONNNNTTTTSSSSEEEETTTT functions. If you specify a single font value to specify an argument that requires a font table, the UIL compiler automatically converts a font value to a font table. CCCCOOOOMMMMPPPPOOOOUUUUNNNNDDDD____SSSSTTTTRRRRIIIINNNNGGGG((((_s_t_r_i_n_g__e_x_p_r_e_s_s_i_o_n[,,,,_p_r_o_p_e_r_t_y[,,,,...]])))) Use the CCCCOOOOMMMMPPPPOOOOUUUUNNNNDDDD____SSSSTTTTRRRRIIIINNNNGGGG function to set properties of a null-terminated string and to convert it into a compound string. The properties you can set are the character set, writing direction, and separator. The result of the CCCCOOOOMMMMPPPPOOOOUUUUNNNNDDDD____SSSSTTTTRRRRIIIINNNNGGGG function is a compound string with the string expression as its value. You can optionally include one or more of the following clauses to specify properties for the resulting compound string: CCCCHHHHAAAARRRRAAAACCCCTTTTEEEERRRR____SSSSEEEETTTT = _c_h_a_r_a_c_t_e_r__s_e_t RRRRIIIIGGGGHHHHTTTT____TTTTOOOO____LLLLEEEEFFFFTTTT = _b_o_o_l_e_a_n__e_x_p_r_e_s_s_i_o_n SSSSEEEEPPPPAAAARRRRAAAATTTTEEEE = _b_o_o_l_e_a_n__e_x_p_r_e_s_s_i_o_n The CCCCHHHHAAAARRRRAAAACCCCTTTTEEEERRRR____SSSSEEEETTTT clause specifies the character set for the string. If you omit the CCCCHHHHAAAARRRRAAAACCCCTTTTEEEERRRR____SSSSEEEETTTT clause, Page 29 (printed 4/30/98) UUUUIIIILLLL((((5555XXXX)))) UUUUNNNNIIIIXXXX SSSSyyyysssstttteeeemmmm VVVV UUUUIIIILLLL((((5555XXXX)))) the resulting string has the same character set as ssssttttrrrriiiinnnngggg____eeeexxxxpppprrrreeeessssssssiiiioooonnnn. The RRRRIIIIGGGGHHHHTTTT____TTTTOOOO____LLLLEEEEFFFFTTTT clause sets the writing direction of the string from right to left if _b_o_o_l_e_a_n__e_x_p_r_e_s_s_i_o_n is True, and left to right otherwise. Specifying this argument does not cause the value of the string expression to change. If you omit the RRRRIIIIGGGGHHHHTTTT____TTTTOOOO____LLLLEEEEFFFFTTTT argument, the resulting string has the same writing direction as _s_t_r_i_n_g__e_x_p_r_e_s_s_i_o_n. The SSSSEEEEPPPPAAAARRRRAAAATTTTEEEE clause appends a separator to the end of the compound string if _b_o_o_l_e_a_n__e_x_p_r_e_s_s_i_o_n is True. If you omit the SSSSEEEEPPPPAAAARRRRAAAATTTTEEEE clause, the resulting string does not have a separator. You cannot use imported or exported values as the operands of the CCCCOOOOMMMMPPPPOOOOUUUUNNNNDDDD____SSSSTTTTRRRRIIIINNNNGGGG function. CCCCOOOOMMMMPPPPOOOOUUUUNNNNDDDD____SSSSTTTTRRRRIIIINNNNGGGG____TTTTAAAABBBBLLLLEEEE((((_s_t_r_i_n_g__e_x_p_r_e_s_s_i_o_n[,,,,...])))) A compound string table is an array of compound strings. Objects requiring a list of string values, such as the XXXXmmmmNNNNiiiitttteeeemmmmssss and XXXXmmmmNNNNsssseeeelllleeeecccctttteeeeddddIIIItttteeeemmmmssss arguments for the list widget, use string table values. The CCCCOOOOMMMMPPPPOOOOUUUUNNNNDDDD____SSSSTTTTRRRRIIIINNNNGGGG____TTTTAAAABBBBLLLLEEEE function builds the values for these two arguments of the list widget. The CCCCOOOOMMMMPPPPOOOOUUUUNNNNDDDD____SSSSTTTTRRRRIIIINNNNGGGG____TTTTAAAABBBBLLLLEEEE function generates a value of type ssssttttrrrriiiinnnngggg____ttttaaaabbbblllleeee. The name SSSSTTTTRRRRIIIINNNNGGGG____TTTTAAAABBBBLLLLEEEE is a synonym for CCCCOOOOMMMMPPPPOOOOUUUUNNNNDDDD____SSSSTTTTRRRRIIIINNNNGGGG____TTTTAAAABBBBLLLLEEEE. The strings inside the string table can be simple strings, which the UIL compiler automatically converts to compound strings. AAAASSSSCCCCIIIIZZZZ____SSSSTTTTRRRRIIIINNNNGGGG____TTTTAAAABBBBLLLLEEEE((((_s_t_r_i_n_g__e_x_p_r_e_s_s_i_o_n[,,,,...])))) An ASCIZ string table is an array of ASCIZ (null- terminated) string values separated by commas. This function allows you to pass more than one ASCIZ string as a callback tag value. The AAAASSSSCCCCIIIIZZZZ____SSSSTTTTRRRRIIIINNNNGGGG____TTTTAAAABBBBLLLLEEEE function generates a value of type aaaasssscccciiiizzzz____ttttaaaabbbblllleeee. The name AAAASSSSCCCCIIIIZZZZ____TTTTAAAABBBBLLLLEEEE is a synonym for AAAASSSSCCCCIIIIZZZZ____SSSSTTTTRRRRIIIINNNNGGGG____TTTTAAAABBBBLLLLEEEE. WWWWIIIIDDDDEEEE____CCCCHHHHAAAARRRRAAAACCCCTTTTEEEERRRR((((_s_t_r_i_n_g__e_x_p_r_e_s_s_i_o_n)))) Use the WWWWIIIIDDDDEEEE____CCCCHHHHAAAARRRRAAAACCCCTTTTEEEERRRR function to generate a wide character string from null-terminated string in the current locale. CCCCLLLLAAAASSSSSSSS____RRRREEEECCCC____NNNNAAAAMMMMEEEE((((_s_t_r_i_n_g__e_x_p_r_e_s_s_i_o_n)))) Use the CCCCLLLLAAAASSSSSSSS____RRRREEEECCCC____NNNNAAAAMMMMEEEE function to generate a widget class name. For a widget class defined by the toolkit, the string argument is the name of the class. For a user-defined widget, the string argument is the name of Page 30 (printed 4/30/98) UUUUIIIILLLL((((5555XXXX)))) UUUUNNNNIIIIXXXX SSSSyyyysssstttteeeemmmm VVVV UUUUIIIILLLL((((5555XXXX)))) the creation routine for the widget. IIIINNNNTTTTEEEEGGGGEEEERRRR____TTTTAAAABBBBLLLLEEEE((((_i_n_t_e_g_e_r__e_x_p_r_e_s_s_i_o_n[,,,,...])))) An integer table is an array of integer values separated by commas. This function allows you to pass more than one integer per callback tag value. The IIIINNNNTTTTEEEEGGGGEEEERRRR____TTTTAAAABBBBLLLLEEEE function generates a value of type iiiinnnntttteeeeggggeeeerrrr____ttttaaaabbbblllleeee. AAAARRRRGGGGUUUUMMMMEEEENNNNTTTT((((_s_t_r_i_n_g__e_x_p_r_e_s_s_i_o_n[,,,, _a_r_g_u_m_e_n_t__t_y_p_e])))) The AAAARRRRGGGGUUUUMMMMEEEENNNNTTTT function defines the arguments to a user- defined widget. Each of the objects that can be described by UIL permits a set of arguments, listed in Appendix B. For example, XXXXmmmmNNNNhhhheeeeiiiigggghhhhtttt is an argument to most objects and has integer data type. To specify height for a user-defined widget, you can use the built-in argument name XXXXmmmmNNNNhhhheeeeiiiigggghhhhtttt, and specify an integer value when you declare the user-defined widget. You do not use the AAAARRRRGGGGUUUUMMMMEEEENNNNTTTT function to specify arguments that are built into the UIL compiler. The _s_t_r_i_n_g__e_x_p_r_e_s_s_i_o_n name is the name the UIL compiler uses for the argument in the UID file. the _a_r_g_u_m_e_n_t__t_y_p_e is the type of value that can be associated with the argument. If you omit the second argument, the default type is AAAANNNNYYYY and no value type checking occurs. Use one of the following keywords to specify the argument type: +o ANY +o ASCIZ_TABLE +o BOOLEAN +o COLOR +o COLOR_TABLE +o COMPOUND_STRING +o FLOAT +o FONT +o FONT_TABLE +o FONTSET +o ICON Page 31 (printed 4/30/98) UUUUIIIILLLL((((5555XXXX)))) UUUUNNNNIIIIXXXX SSSSyyyysssstttteeeemmmm VVVV UUUUIIIILLLL((((5555XXXX)))) +o INTEGER +o INTEGER_TABLE +o REASON +o SINGLE_FLOAT +o STRING +o STRING_TABLE +o TRANSLATION_TABLE +o WIDE_CHARACTER +o WIDGET You can use the AAAARRRRGGGGUUUUMMMMEEEENNNNTTTT function to allow the UIL compiler to recognize extensions to the Motif Toolkit. For example, an existing widget may accept a new argument. Using the AAAARRRRGGGGUUUUMMMMEEEENNNNTTTT function, you can make this new argument available to the UIL compiler before the updated version of the compiler is released. RRRREEEEAAAASSSSOOOONNNN((((_s_t_r_i_n_g__e_x_p_r_e_s_s_i_o_n)))) The RRRREEEEAAAASSSSOOOONNNN function is useful for defining new reasons for user-defined widgets. Each of the objects in the Motif Toolkit defines a set of conditions under which it calls a user-defined function. These conditions are known as callback reasons. The user-defined functions are termed callback procedures. In a UIL module, you use a callbacks list to specify which user-defined functions are to be called for which reasons. Appendix B lists the callback reasons supported by the Motif Toolkit objects. When you declare a user-defined widget, you can define callback reasons for that widget using the RRRREEEEAAAASSSSOOOONNNN function. The string expression specifies the argument name stored in the UID file for the reason. This reason name is supplied to the widget creation routine at run time. TTTTRRRRAAAANNNNSSSSLLLLAAAATTTTIIIIOOOONNNN____TTTTAAAABBBBLLLLEEEE((((_s_t_r_i_n_g__e_x_p_r_e_s_s_i_o_n[,,,,...])))) Each of the Motif Toolkit widgets has a translation table that maps X events (for example, mouse button 1 being pressed) to a sequence of actions. Through widget Page 32 (printed 4/30/98) UUUUIIIILLLL((((5555XXXX)))) UUUUNNNNIIIIXXXX SSSSyyyysssstttteeeemmmm VVVV UUUUIIIILLLL((((5555XXXX)))) arguments, such as the common translations argument, you can specify an alternate set of events or actions for a particular widget. The TTTTRRRRAAAANNNNSSSSLLLLAAAATTTTIIIIOOOONNNN____TTTTAAAABBBBLLLLEEEE function creates a translation table that can be used as the value of a argument that is of the data type ttttrrrraaaannnnssssllllaaaattttiiiioooonnnn____ttttaaaabbbblllleeee. You can use one of the following translation table directives with the TTTTRRRRAAAANNNNSSSSLLLLAAAATTTTIIIIOOOONNNN____TTTTAAAABBBBLLLLEEEE function: ####oooovvvveeeerrrrrrrriiiiddddeeee, ####aaaauuuuggggmmmmeeeennnntttt, or ####rrrreeeeppppllllaaaacccceeee. The default is ####rrrreeeeppppllllaaaacccceeee. If you specify one of these directives, it must be the first entry in the translation table. The ####oooovvvveeeerrrrrrrriiiiddddeeee directive causes any duplicate translations to be ignored. For example, if a translation for <BBBBttttnnnn1111DDDDoooowwwwnnnn> is already defined in the current translations for a PushButton, the translation defined by _n_e_w__t_r_a_n_s_l_a_t_i_o_n_s overrides the current definition. If the ####aaaauuuuggggmmmmeeeennnntttt directive is specified, the current definition takes precedence. The ####rrrreeeeppppllllaaaacccceeee directive replaces all current translations with those specified in the XXXXmmmmNNNNttttrrrraaaannnnssssllllaaaattttiiiioooonnnnssss resource. RRRREEEELLLLAAAATTTTEEEEDDDD IIIINNNNFFFFOOOORRRRMMMMAAAATTTTIIIIOOOONNNN uuuuiiiillll((((1111XXXX)))), UUUUiiiillll((((3333XXXX)))) Page 33 (printed 4/30/98)